/****************************************************************************
 * Copyright (C) 2025 Chenyz. All rights reserved.
 *
 * @file    my_multi_button.h
 *
 * @par     dependencies
 *          - stdint.h
 *          - stdbool.h
 *          - string.h
 *
 * @author  Chenyz
 *
 * @brief   Advanced multi-button handler module with following features:
 *          - Event detection (Press/Release/Single/Double/Triple Click/Long Press)
 *          - Hardware-agnostic architecture for easy portability
 *          - Finite state machine implementation
 *          - Configurable debounce timing parameters
 *          - Support multiple independent button instances
 *          - Event callback registration system
 *          - Cross-platform compatibility (bare-metal/RTOS environments)
 *
 * @version V1.0
 * @date    2025-05-23
 *
 * @note    Coding standard:
 *          - 4 spaces per indent level
 *          - Follow MISRA-C 2012 guidelines
 *          - Compiler compatibility: ISO C99 and newer
 *
 ****************************************************************************/

#ifndef __MY_MULTI_BUTTON_H__
#define __MY_MULTI_BUTTON_H__

/******************************** Includes *********************************/
#include <stdbool.h>
#include <stdint.h>
#include <string.h>

/******************************** Defines **********************************/
/* Event Types */
#define BUTTON_PRESS_DOWN       (0U)
#define BUTTON_PRESS_UP         (1U)
#define BUTTON_DOUBLE_CLICK     (2U)
#define BUTTON_TRIPLE_CLICK     (3U)
#define BUTTON_LONG_PRESS_START (4U)
#define BUTTON_LONG_PRESS_HOLD  (5U)
#define BUTTON_NO_EVENT         (0xFFU)
/* State Machine States */
#define BUTTON_IDLE_STATE                 (0U)
#define BUTTON_PRESS_STATE                (1U)
#define BUTTON_RELEASE_STATE              (2U)
#define BUTTON_DOUBLE_CLICK_STATE         (3U)
#define BUTTON_DOUBLE_CLICK_RELEASE_STATE (4U)
#define BUTTON_TRIPLE_CLICK_STATE         (5U)
#define BUTTON_HOLDING_STATE              (6U)
/* Electrical Characteristics */
#define BUTTON_ACTIVE_LOW  (0U)
#define BUTTON_ACTIVE_HIGH (1U)
/* Timing Configuration */
#define SCAN_INTERVAL_MS     (5U)
#define DEBOUNCE_TICKS       (3U)
#define SHORT_PRESS_THRESH   (500U / SCAN_INTERVAL_MS)
#define LONG_PRESS_THRESH    (3000U / SCAN_INTERVAL_MS)
#define MAX_SUPPORTED_EVENTS (6U)

/***************************** Type Definitions ****************************/
typedef void (*ButtonEventHandler)(void);
typedef struct ButtonContext
{
    uint8_t               state;
    uint16_t              hold_duration;
    uint8_t               debounce_counter;
    uint8_t               current_event;
    uint8_t               click_count;
    uint8_t               (*get_hw_level)(uint8_t button_id);
    uint8_t               active_level;
    uint8_t               current_level;
    uint8_t               id;
    struct ButtonContext *next;
    ButtonEventHandler    event_handlers[MAX_SUPPORTED_EVENTS];
} ButtonContext;

/*************************** Function Declarations **************************/
/* Initialization and Configuration */
void Button_Init(ButtonContext *ctx,
                 uint8_t        (*get_level_fn)(uint8_t),
                 uint8_t        active_polarity,
                 uint8_t        button_id);

/* Core Processing Functions */
void Button_UpdateState(ButtonContext *ctx);
void Button_ProcessAll(void);
/* Event Management */
bool Button_RegisterHandler(ButtonContext     *ctx,
                            uint8_t            event_type,
                            ButtonEventHandler handler);

bool Button_UnregisterHandler(uint8_t button_id, uint8_t event_type);
/* Instance Management */
bool Button_AddInstance(ButtonContext *ctx);
bool Button_RemoveInstance(uint8_t button_id);
/* Status Query */
uint8_t Button_GetCurrentEvent(const ButtonContext *ctx);

#endif /* __MY_MULTI_BUTTON_H__ */